home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / bbsutil / dgbg100.zip / DGBG.DOC next >
Text File  |  1991-02-24  |  18KB  |  440 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.         ┌── Thanks for considering DGBG! ──────────────────────────────┐
  7.         │                                                              │
  8.         │                                                              │
  9.         │                                                              │
  10.         │           DGBG is The Darn Good Bulletin Generator           │
  11.         │                       ^    ^    ^        ^                   │
  12.         │               Copyright 1991, Brian McCormick                │
  13.         │                                                              │
  14.         │                                                              │
  15.         │                                                              │
  16.         └───────────────────────────────────────────────── DGBG 1.00 ──┘
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.      Distribution and Liability Statement:
  47.  
  48.          This software is free, and may be distributed for free to other
  49.          people.  Charging a fee for this software is a violation of the
  50.          author's copyright.  As usual with software of this nature, no
  51.          warranty either stated or implied is offered.  By using this
  52.          software, you agree that you assume all liability in connection
  53.          with its use or misuse.
  54.  
  55.      What is DGBG?
  56.  
  57.          DGBG was designed for the purpose of compiling a visually
  58.          appealing news bulletin for use on BBS's.  DGBG is only one
  59.          of many such programs, but it supports more useful features
  60.          and is more visually appealing than any similar program this
  61.          author has seen.  Among the features that DGBG supports:
  62.  
  63.             *  DGBG creates ANSI (.ANS), ASCII (.ASC), and
  64.                AVATAR (.AVT) files.
  65.  
  66.             *  Each news item is displayed in a window of its
  67.                own.
  68.  
  69.             *  Input text is automatically line wrapped for an
  70.                optimal fit within display windows.
  71.  
  72.             *  Each window can be independently positioned, and
  73.                will overlap previously drawn windows.
  74.  
  75.             *  The background color, text color, frame color,
  76.                frame style, highlight color, and title can be
  77.                set individually for each window.
  78.  
  79.             *  Sequential display of windows with overlap is
  80.                supported in ASCII, ANSI, and AVATAR output files.
  81.  
  82.  
  83.  
  84.      How to use DGBG
  85.  
  86.          DGBG works in much the same way as other news bulletin
  87.          compilers.  Like other news bulletin compilers, this program
  88.          scans an input file containing message text and control
  89.          parameters.  The information contained within that file is
  90.          used to produce up to three output files, one containing ANSI
  91.          terminal control information, one a flat ASCII file, and the
  92.          last an optional AVATAR output file.  The ASCII file contains
  93.          no terminal control information other than screen clearing
  94.          codes.  Both files are elaborately formatted and decorated to
  95.          produce a visually appealing display.
  96.  
  97.          The default input file for DGBG is called DGBG.TXT, and it
  98.          should be present within the directory that DGBG is invoked
  99.          from.  DGBG will look for that file when it starts up, and
  100.          will abort with an error message if the file is not found.
  101.          DGBG can be forced to process a file other than DGBG.TXT by
  102.          providing the name of that file on the command line.  If this
  103.          option is used, all references to DGBG.TXT in this document
  104.          can be considered to apply to the file specified.
  105.  
  106.  
  107.  
  108.  
  109.                                     2
  110.          Since DGBG.TXT contains both message text and formatting
  111.          commands, there must be a way for DGBG to distinguish
  112.          between the two.  Formatting commands are therefore dis-
  113.          tinguished from message text by the fact that all commands
  114.          start with an asterisk ("*") and must begin in the first
  115.          text column.  Without going into any detail as yet into what
  116.          the various commands mean, the following simple illustration
  117.          should show how commands are distinguished from text:
  118.  
  119.             *Title Simple Illustration
  120.             This is a line of text
  121.  
  122.             This is another line of text
  123.             *Style 4
  124.             *Window
  125.  
  126.          All the lines beginning with an asterisk are formatting
  127.          commands, and all the rest of the lines (including the blank
  128.          one) are lines of message text.
  129.  
  130.          Text input into the DGBG control file is a fairly straight-
  131.          forward task.  Simply entering the text in paragraph format
  132.          will work.  Line length is not especially important since
  133.          any input text will automatically be line wrapped to a length
  134.          of 60 characters per line.  Input lines should not exceed 110
  135.          characters though, for longer lines may be truncated.
  136.  
  137.          The line wrapping algorithm in DGBG keys on two things to
  138.          determine when to end a paragraph of text and begin a new one.
  139.          The first of these is a blank line.  Any blank line will cause
  140.          DGBG to finish the current paragraph, skip a line, and begin
  141.          the next one.  Vertical spacing with blank lines is thereby
  142.          preserved in the output files.  A line beginning with a space
  143.          (such as a paragraph indention) will also trigger the end of
  144.          the current paragraph and the beginning of a new one.  In this
  145.          case however, no lines are skipped between paragraphs.  The
  146.          indention is preserved however, and thus horizontal spacing is
  147.          preserved in the output file.  DGBG's line wrapping algorithm
  148.          does NOT remove extra blanks between individual words unless a
  149.          line break also occurs between those words.
  150.  
  151.          The real power of DGBG is not derived merely from simple text
  152.          input, however.  What makes DGBG special is the ability to
  153.          configure multiple overlapping windows, each with its own
  154.          individual characteristics.  This is accomplished through the
  155.          use of a set of formatting commands.
  156.  
  157.          DGBG's commands essentially fall into two categories:  the
  158.          Window command and all the rest.  All the commands except the
  159.          Window command are used to set various parameters which will
  160.          be used when the window command is invoked to determine what
  161.          characteristics (such as location, color, etc.) a window will
  162.          have when it is displayed.  Each time a command other than the
  163.  
  164.                                     3
  165.          Window command (with some exceptions, as will be seen later)
  166.          is invoked, the value of the setting controlled by that command
  167.          is changed.  The order of commands is not important, as long as
  168.          all the desired characteristics of a command are established
  169.          before the Window command is used.  A command occurring twice
  170.          before a Window command will not cause an error.  The last
  171.          value given will be the one used when the window is written to
  172.          the output files.
  173.  
  174.          Text is processed in a manner similar to the way non-Window
  175.          commands are processed.  It is saved up until a Window
  176.          command is reached, and then it is all put into the display
  177.          window at once.
  178.  
  179.  
  180.      DGBG Commands
  181.  
  182.          Following this section is an alphabetical listing of all
  183.          the commands supported by DGBG.  For each command, both a
  184.          description and a syntax definition are given.
  185.  
  186.          This document describes the function of DGBG's commands in
  187.          ordinary English, and therefore their purpose should be
  188.          reasonably self evident.  The syntax definitions may not be
  189.          so obvious however, and so the following descriptions are
  190.          given:
  191.  
  192.             *Command <1..10>
  193.  
  194.             This syntax means that the (purely hypothetical) command
  195.             "Command" would accept an integer between 1